File Management Subs.

This part of the program will talk about the way the program starts up. One method is to 
double click on this programs icon and let Windows open it as with any other executable.
Another way is to drag and drop the icon of that FILE.ICO of interest into this program's 
Icon. Our program must deal with each method a little differently.

We already discussed how the QTimer vectors to a sub-routine named INIT when it is first 
activated. This session will talk about what happens after the half second time out. 
We can already see that program begins with the INIT sub-routime.

 INIT begins it all. First it is disabled by setting the enabled parameter to 0.
      Otherwise the program would re-vector to INIT every half second as long as
      the QTimer was enabled. QTimer is activated by default as enabled= 1 or ON 

      Commandcount is a program internal variable that provides the number of objects
      in the command$ array. Double clicking to start our program results in no 
      file names stored in the command$() array and commandcount= 0. If a program
      icon is dropped into this programs icon to RUN it, the commandcount = 1 and
      the filename in command$(1) would be the file name of the icon dropped into it.

   IF commandcount= 0 (double click start) then the ELSE code is executed, clearing 
      the xHEX QRichEdit object, and posting the message to use the OPEN button to
      select an input file and returning to the SHOWMODAL instructing and waiting.

   IF commancount= 1 then variable FNAME$ will take the dropped FILE and vector to 
      the xRUN sub routine to be serviced. On completion, the program will return to
      the ELSE statement, ignore it, satisfy the END IF statement and the END SUB 
      statement and return to the SHOWMODAL instruction for operator intervention.
      Remamber that xRUN is the starting point for handling the Icon file in FNAME$

 xOPEN is the sub that the operator was prompted to use if the program was opened with 
      a double click. No file has yet been selected. Click the xOpen button and the 
      program opens on Sub xOpen. 
   If OpenDialog.Execute calls QOpenDialog and prompts selection of a file name to open.
      Zero indicates the selection was cancelled resulting in setting the eoz byte 
        counter to 0 and exiting the sub, returning to SHOWMODAL, waiting for an event.
      One indicates a file was selected and the name of the file will be in the variable
        named OpenDialog.Filename. copy it to variable FNAME$ and vector to xRun.

 xRUN is where the drag-drop vectored after capturing our input file into FNAME$. Either 
      method of starting the program follows this common path now.  
      FileStream.open opens FNAME$ as fmOpenRead and stores the data bytes into memory. 
      FileStream.LoadArray copies the bytes into z(0) and FileStream.Size as bytecount.
      the byte count (766) is stored in eoz before closing the filestream. 
      I don't like to keep a file opened any longer than necessary, in case of power loss
      or an irregular program termination. 
      At this point, z() array holds the data bytes and eoz holds our byte count.
      the program then vectors to xRestore.

 xRestore begins after the icon file is loaded or any time the RESTORE Qbutton is closed.
      It calls the xOFFSET and xHEX routines that display the addresses and the data bytes.
   If eoz is not 765 (0 through 765 is 766 bytes) then a warning is posted.
      Notice the _ at the end of the lines. It provides line contiunation so that the 
      entire IF statement is on one line, needing no END IF statement.
      This sub-module then vectors to xPost which draws the data for us to view and edit.
      xPost will be covered later. When it is completed, program control returns here and 
      goes back to SHOWMODAL to await something intelligent from the program operator.
      xOFFSET and xHEX will also be covered in a different session.

 xSave is the reciprical function of the xOpen function. The edited byte data is loaded 
      into the z() array and sent back out to the disk with the filename provided with 
      the SaveDialog QObject. The selection process is the same, except that the operator 
      provides the file name for the new icon file. The filestream is closed and program 
      execution returns to the SHOWMODAL state.
      xNewZ is a sub-routine that copies the Edited byte data in the xHEX display back 
      into the z() array for subsequent output to the disk. It too will be covered later.

''''''''''''''''''''' File handling subs '''''''''''''''''

sub Init
         irig.enabled= 0
      If commandcount > 0 then
         FNAME$ = command$(1)
         xRun
     Else
         eHex.Clear
         eHex.Addstrings "   Click the OPEN Button "
         eHex.Addstrings "          then           "
         eHex.Addstrings "    Select an Icon File  "
     End IF
 end sub

'''' else select the ico file with the open button
 Sub xopen
  If OpenDialog.Execute = 0   Then eoz= 0: exit sub
     FNAME$ = opendialog.filename
     xRun
 end Sub

'''' common load and run module for xDragDrop and xopen
 Sub xRun
         FileStream.Open( FNAME$, fmOpenRead)
         FileStream.LoadArray(z(0),FileStream.Size)
         eoz = FileStream.size-1
         FileStream.close
         xRestore
 end sub

Sub xRestore
         xoffset
         xhex
      IF eoz <> 765 then showmessage " this is not a 766 byte file"_
         +chr$(13)+"the graphics display will be other"_
         +chr$(13)+"then that of a RapidQ .ico file"
     xpost
 end sub

Sub xSave
         xnewZ
      If SaveDialog.Execute then
         FileStream.Open(SAVEdialog.filename, fmcreate)
         FileStream.SaveArray(z(),eoz+1)
         FileStream.Close
     End If
 end sub

That is a lot of explaination for such a short section of code. It does do a lot of work
for us though. The need for seperate sub routines, rather than one single module is
because some of the routines are callable from SHOWMODAL with a QButton closure. This 
might be a good time to practice using flow diagrams to show the program execution. It 
will also ensure that there are no return addresses left dangling from unsatisfied 
sub return closures. Everything should happily return to SHOWMODAL, waiting for the next 
mouse closure to do something useful.

Softalk

It is a good idea to get a good feeling for a running program when openig and closing
files on the hard drive, floppy or any other mass storage device. Garbage files can be 
splattered who knows where if it isn't done carefully. It may never cause problems, but 
would be terrible house keeping.

QfileStreams and QMemoryStreams are a very elegant way of handling data in memory and 
on the mass storage devices. We used a simple ARRAY for this example; however we could
have just as easily used QMemoryStream. For the purposes of learning how to use file 
transfer and processing, this is probably a good exercise because it limits the need to 
use too many QObjects in one session. And it gets the job done comprehensively.

Play around with these modules, but keep in mind that there is a possibility of clobbering 
a disk file or creating some mavericks that have to be searched out later. I make a point 
of using file names that are easily found on the hard drive if I have to go looking for 
them with the Windows Search feature.

........ In any case .......
....... Happy Hacking ......